<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Using a Conventional Modular Directory Structure - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.controller.modular.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.controller.modular.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.controller.plugins.html">Plugins</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.controller.html">Zend_Controller</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.controller.exceptions.html">MVC Exceptions</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.controller.modular" class="section"><div class="info"><h1 class="title">Using a Conventional Modular Directory Structure</h1></div>
    

    <div class="section" id="zend.controller.modular.introduction"><div class="info"><h1 class="title">Introduction</h1></div>
        

        <p class="para">
            The Conventional Modular directory structure allows you to separate
            different <acronym class="acronym">MVC</acronym> applications into self-contained units, and re-use
            them with different front controllers. To illustrate such a
            directory structure:
        </p>

        <pre class="programlisting brush: txt">
docroot/
    index.php
application/
    default/
        controllers/
            IndexController.php
            FooController.php
        models/
        views/
            scripts/
                index/
                foo/
            helpers/
            filters/
    blog/
        controllers/
            IndexController.php
        models/
        views/
            scripts/
                index/
            helpers/
            filters/
    news/
        controllers/
            IndexController.php
            ListController.php
        models/
        views/
            scripts/
                index/
                list/
            helpers/
            filters/
</pre>


        <p class="para">
            In this paradigm, the module name serves as a prefix to the
            controllers it contains. The above example contains three
            module controllers, &#039;<span class="classname">Blog_IndexController</span>&#039;,
            &#039;<span class="classname">News_IndexController</span>&#039;, and
            &#039;<span class="classname">News_ListController</span>&#039;.
            Two global controllers, &#039;<span class="classname">IndexController</span>&#039; and
            &#039;<span class="classname">FooController</span>&#039; are also defined; neither of these will be
            namespaced. This directory structure will be used for examples in
            this chapter.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>No Namespacing in the Default Module</b><br /></span>
            

            <p class="para">
                Note that in the default module, controllers do not need a
                namespace prefix. Thus, in the example above, the controllers in
                the default module do not need a prefix of &#039;Default_&#039; -- they
                are simply dispatched according to their base controller name:
                &#039;<span class="classname">IndexController</span>&#039; and
                &#039;<span class="classname">FooController</span>&#039;. A namespace prefix is
                used in all other modules, however.
            </p>
        </p></blockquote>

        <p class="para">
            So, how do you implement such a directory layout using the Zend
            Framework <acronym class="acronym">MVC</acronym> components?
        </p>
    </div>

    <div class="section" id="zend.controller.modular.directories"><div class="info"><h1 class="title">Specifying Module Controller Directories</h1></div>
        

        <p class="para">
            The first step to making use of modules is to modify how you specify
            the controller directory list in the front controller. In the basic
            <acronym class="acronym">MVC</acronym> series, you pass either an array or a string to
             <span class="methodname">setControllerDirectory()</span>, or a path to
             <span class="methodname">addControllerDirectory()</span>. When using modules, you need
            to alter your calls to these methods slightly.
        </p>

        <p class="para">
            With  <span class="methodname">setControllerDirectory()</span>, you will need to pass an
            associative array and specify key and value pairs of module
            name and directory paths. The special key <span class="property">default</span> will be
            used for global controllers (those not needing a module namespace).
            All entries should contain a string key pointing to a single path,
            and the <span class="property">default</span> key must be present. As an example:
        </p>

        <pre class="programlisting brush: php">
$front-&gt;setControllerDirectory(array(
    &#039;default&#039; =&gt; &#039;/path/to/application/controllers&#039;,
    &#039;blog&#039;    =&gt; &#039;/path/to/application/blog/controllers&#039;
));
</pre>


        <p class="para">
             <span class="methodname">addControllerDirectory()</span> will take an optional second
            argument. When using modules, pass the module name as the second
            argument; if not specified, the path will be added to the
            <em class="emphasis">default</em> namespace. As an example:
        </p>

        <pre class="programlisting brush: php">
$front-&gt;addControllerDirectory(&#039;/path/to/application/news/controllers&#039;,
                               &#039;news&#039;);
</pre>


        <p class="para">
            Saving the best for last, the easiest way to specify module
            directories is to do so en masse, with all modules under a common
            directory and sharing the same structure. This can be done with
             <span class="methodname">addModuleDirectory()</span>:
        </p>

        <pre class="programlisting brush: php">
/**
 * Assuming the following directory structure:
 * application/
 *     modules/
 *         default/
 *             controllers/
 *         foo/
 *             controllers/
 *         bar/
 *             controllers/
 */
$front-&gt;addModuleDirectory(&#039;/path/to/application/modules&#039;);
</pre>


        <p class="para">
            The above example will define the <em class="emphasis">default</em>,
            <em class="emphasis">foo</em>, and <em class="emphasis">bar</em> modules, each pointing to the
            <var class="filename">controllers/</var> subdirectory of their respective module.
        </p>

        <p class="para">
            You may customize the controller subdirectory to use within your
            modules by using  <span class="methodname">setModuleControllerDirectoryName()</span>:
        </p>

        <pre class="programlisting brush: php">
/**
 * Change the controllers subdirectory to be &#039;con&#039;
 * application/
 *     modules/
 *         default/
 *             con/
 *         foo/
 *             con/
 *         bar/
 *             con/
 */
$front-&gt;setModuleControllerDirectoryName(&#039;con&#039;);
$front-&gt;addModuleDirectory(&#039;/path/to/application/modules&#039;);
</pre>


        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                You can indicate that no controller subdirectory be used for your
                modules by passing an empty value to
                 <span class="methodname">setModuleControllerDirectoryName()</span>.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.controller.modular.router"><div class="info"><h1 class="title">Routing to Modules</h1></div>
        

        <p class="para">
            The default route in <span class="classname">Zend_Controller_Router_Rewrite</span> is
            an object of type <span class="classname">Zend_Controller_Router_Route_Module</span>.
            This route expects one of the following routing schemas:
        </p>

        <ul class="itemizedlist">
            <li class="listitem"><p class="para"><var class="filename">:module/:controller/:action/*</var></p></li>
            <li class="listitem"><p class="para"><var class="filename">:controller/:action/*</var></p></li>
        </ul>

        <p class="para">
            In other words, it will match a controller and action by themselves
            or with a preceding module. The rules for matching specify that a
            module will only be matched if a key of the same name exists in the
            controller directory array passed to the front controller and
            dispatcher.
        </p>
    </div>

    <div class="section" id="zend.controller.modular.defaultcontroller"><div class="info"><h1 class="title">Module or Global Default Controller</h1></div>
        

        <p class="para">
            In the default router, if a controller was not specified in the <acronym class="acronym">URL</acronym>,
            a default controller is used (<span class="classname">IndexController</span>, unless
            otherwise requested). With modular controllers, if a module has been
            specified but no controller, the dispatcher first looks for this
            default controller in the module path, and then falls back on the
            default controller found in the &#039;default&#039;, global, namespace.
        </p>

        <p class="para">
            If you wish to always default to the global namespace, set the
            <var class="varname">$useDefaultControllerAlways</var> parameter in the front controller:
        </p>

        <pre class="programlisting brush: php">
$front-&gt;setParam(&#039;useDefaultControllerAlways&#039;, true);
</pre>

    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.controller.plugins.html">Plugins</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.controller.html">Zend_Controller</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.controller.exceptions.html">MVC Exceptions</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.controller.html">Zend_Controller</a></li>
  <li><a href="zend.controller.quickstart.html">Zend_Controller Quick Start</a></li>
  <li><a href="zend.controller.basics.html">Zend_Controller Basics</a></li>
  <li><a href="zend.controller.front.html">The Front Controller</a></li>
  <li><a href="zend.controller.request.html">The Request Object</a></li>
  <li><a href="zend.controller.router.html">The Standard Router</a></li>
  <li><a href="zend.controller.dispatcher.html">The Dispatcher</a></li>
  <li><a href="zend.controller.action.html">Action Controllers</a></li>
  <li><a href="zend.controller.actionhelpers.html">Action Helpers</a></li>
  <li><a href="zend.controller.response.html">The Response Object</a></li>
  <li><a href="zend.controller.plugins.html">Plugins</a></li>
  <li class="active"><a href="zend.controller.modular.html">Using a Conventional Modular Directory Structure</a></li>
  <li><a href="zend.controller.exceptions.html">MVC Exceptions</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>